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By Karl Thompson 


A Table Documentor 


Documenting Database Tables with a Delphi Utility 


elphi is a wonderful tool, but it does have a few omissions. For exam- 

ple, Delphi cannot print table structures. The Database Desktop allows 

you to view a table’s structure, but cannot print it for you. Of course, 
you could always save the structure information to a table, and then create and 
print a report of its contents. 


The Table Documentor utility presented =| Super Duper Table Documentor 
‘ . ; ; : File Fonts Help 
in this article (see Figure 1) does just 
that. It can display or print Paradox or Available Files: 5 —— = document: 
P : animals.dbf iolife.d 
dBASE table structures with just a few argue | eieteinacab 
mouse clicks. clients.dbt 
country.db 
customer.db 


Furthermore, it isn’t limited to showing sd is danare : 
Or printing just one structure at a time. 
The user can navigate the hard disk, 
select a number of tables (within memo- 
ry limits), and the Table Documentor 


will analyze and process all the tables. Tables (*DB:*DBF) || 
This makes the utility particularly handy 


for comparing table structures. Show Structures 


Using the Utility Figure 1: The Table Documentor at run time. 
Before viewing its code, test the pro- 





gram. Due to Windows user interface conventions, the program is easy to use, but you should 

note some of its more subtle features. For example, you can select files using one of three 

techniques: 

¢ Double-click on each file name to add it to the list box on the right. (There is no limit to the 
number of files that can be documented at one time.) 

¢ Click on a file and hold or while continuing to select files. When all the appropriate files 
are selected, click on the > button. The selected files will move to the ... tables to document list. 

¢ Click the >> button and all the tables in the current directory will be documented. If the 
directory contains Paradox and dBASE tables, you may limit the selection to one or the other 
via the pick list above the Print Structures button. (Figure 2 shows the structures of two tables 
being displayed.) You can follow similar steps to deselect files. 


Delphi INFORMANT A 19 


DATASOURCE 1 


=| super Duper Table Documentor a 
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# Field Name 
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Figure 2: Form2 (Structure Form) in action. 


By default, the Table Documentor does not save the path to 
the file. However, to document tables in different directories, 
the Table Documentor must keep track of the tables’ loca- 
tions. You can change the default behavior under the File 
menu. When Save Path is ON, the path will be prepended to 
the file name. (Storing the table’s path is optional since if the 
files are nested several directories deep, then the table name 
may not always be visible in the list box on the right. For aes- 
thetic reasons, I did not want to widen the main form.) 


Another File menu option should also be noted. When Form 
Feed is ON (the default), each structure begins printing on a new 
page. When Form Feed is OFF, the Table Documentor prints 
continuously, regardless of page breaks. 


A Look at the Code 


Many of the classes, properties, and techniques used by the Table 
Documentor have been thoroughly discussed in previous issues 
of Delphi Informant and do not require further explanation. In 
this article, we'll: 

¢ closely examine the FieldDef and IndexDefs properties of the 
T Table. They provide all the information we need about a 
table's structure. 

¢ concentrate on how to handle printing using only Object 
Pascal, thus eliminating the complication of using 
ReportSmith or another report writer. 

e — discuss how to provide users with simple, online help that does 
not require the use of the Window's Help engine. This can be 
handy for small applications such as the Table Documentor, 
since supplying or installing a .HLP file is unnecessary. 


The Table Documentor consists of four forms. The Main Form is 
the interface for the user to select tables for documenting (see 
Figure 3). Form2 has a TMemo component containing the text that 
describes the structure of the tables (see Figure 4). Form3 contains 
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Figure 3 (Top): Form] in design mode. 
Figure 4 (Bottom): Form2 at design time. 


another 7/Memo component for displaying the help text. A fourth 
form is used for an About box. (Note: This About box is not a 
standard Delphi component — it’s freeware written by Jeff 
Atwood. For more information, see the downloadable message at 
the end of the article.) 


Form1 is the most complex form in this project. It uses 14 com- 
ponents arranged on three 7Panels. Panell contains two TLabels, 
as well as a TFileListBox, TDirectoryListBox, TDriveComboBox, 
TListBox, and TFilterComboBox. Panel2 is placed on Panell and 
contains four 7SpeedButtons. A third TPanel contains three 

7 BitBins. Additionally, four non-visual components are used: 
TMainMenu, TPrintDialog, TTable, and TFontDialog. The 
TMemo component that you see in design mode has its Visible 
property set to False (we'll discuss this more later). 


The program’s main functionality is contained within the 
GetStructures function (see Figure 5). A table’s structure is ana- 
lyzed in GetStructures and it’s called whether the structure is 


being displayed or printed. 
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function TForm1.GetStructures(var M: TMemo) Boolean; 
const 

KeyFieldIndicator: String! = ‘*'; 
var 

Tbl1Cnt, FldCnt, X, Y: integer; 

SizeStr: String3; 

KeyChar: String1; 

PrimIndxStr: string; 
begin 

Result := True; 

Screen.Cursor := crHourglass; 

try 


with M, Table1 do begin 


Tb1Cnt := ListBox1.Items.Count - 1; 

Text >= ''s { Remove ListBox's default string } 
PrimIndxStr := ‘None’; 

for X := 0 to TblCnt do begin 


{ 'Add' methods will raise an exception if not 
enough memory } 
DatabaseName := FileListBox1.Directory; 
TableName := ListBox1.Items[ X ]; 
{ Update raises an expection if index can't be 
found or is unknown } 
{ For example: TTable doesn't understand 
Rock-e-t's NSX indexes } 
FieldDefs.Update; 
IndexDefs.Update; 
for Y := 0 to IndexDefs.Count - 
{ Find primary index } 
if ixPrimary in IndexDefs.Items[Y].Options then 
{ Save the fields in the index } 
PrimIndxStr := IndexDefs.Items[Y].Fields; 
{ Items uses a O offset } 
FldCnt:= FieldDefs.Count - 1; 
Lines.Add('Table : ‘' + TableName) ; 
Lines.Add('Field(s) in Primary Index : ' + 
KeyFieldIndicator) ; 
Lines.Add(format('%3s %-25s %-6S %-S', 
['#',' Field Name', 'Type','Required'])); 
for Y := 0 to FldCnt do begin 
if (FieldDefs.Items[Y].Size > 0) then 
SizeStr := IntToStr(FieldDefs.Items[Y].Size) 
else 
{ Size 0 makes no sense for Date type, etc. } 
SizeStr := ''; 
if (Pos(FieldDefs.Items[Y].Name, 
PrimIndxStr) = 0) then 
KeyChar := ' ' 
else 
{ Indicate keyed field } 
KeyChar := KeyFieldIndicator; 
Lines.Add(format(‘'%38d %-25s %1S%-5S %-3s', 
[FieldDefs.Items[Y].FieldNo, 
FieldDefs.Items[Y].Name, 
FieldTypeToAbbrevstring ( 
FieldDefs.Items[Y].DataType) , 
S$izeStr+KeyChar, 
BooleanToYNstring ( 
FieldDefs.Items[Y].Required)])); 
{ Inner field loop } 


1 do 


end; 


{ Don't FormFeed after last table, or if 


menu's FormFeed is not selected } 


if Printing and 
X < TbhlCnt and 
FormFeed1.Checked then 
begin 
Lines.Add(#12); { FormFeed character } 
end 
else 
begin 


Lines.Add('') 
Lines.Add('' ) 
end; 


{ Blank lines } 


b 
I 


end; { Outer table loop } 
end; 
finally 
Screen.Cursor := crDefault; 
end; 
end; 


Figure 5: The GetStructures function. 
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In general, Pascal-type strings (managed by a TString object) 
are being initialized so that one string contains detail informa- 
tion about each field in a table. There are also three header 
strings that store the table’s name, a legend row, and a title 
row. The string object that is being initialized is a property of 
a [Memo object. 


The GetStructures function contains an outer loop and two inner 
loops that are not nested. The outer loop is used to iterate 
through each table in the ListBox1, and to initialize or update 
four TTable properties. The current table being documented is 
assigned to the 7able1. TableName property. Its path is assigned to 
Table1.DatabaseName. 


Table1.FieldDefs and Table1 IndexDefs are the two key properties 
that provide information about a table's structure. The FieldDefs 
object is of type 7FieldDefs and contains two properties: Count 
stores the total number of fields in the table; and /tems is an array 
of pointers to FieldDef objects. The FieldDef objects are of type 
TFieldDef and define properties such as DataType, FieldNo, Name, 
and Size. These hold information about the individual fields. To 
initialize each FieldDef and subsequently Table1.FieldDefs, a call 
must be made to the FieldDefs. Update method. 


At this point, you may wonder why the 7 Table. Field property 
was not used to gather the structure information. The reason lies 
in the way Field and FieldDefs are initialized. It’s important to 
note that FieldDefs does not require the underlying table to be 
open when it’s initialized. 


FieldCount’s value could have been easily used to initialize an 
index for iterating through 7able1.Field — which would obtain 
field names and datatypes. However, this requires that 7ab/el be 
opened (i.e. that 7Zablel.Active be set to True) and obviously, 
opening the table is not always possible. 


Because updating FieldDefs does not require the table to be 
open, the Table Documentor can always show the table’s struc- 
ture regardless of another application’s interaction with the table. 


The second 7 7able property that we are most concerned with is 
IndexDefs, an object of type TIndexDefs. This class has the same 
two properties as 7FieldDefs, but in this case the /tems property 
is an array of pointers to instances of 77ndexDef. One instance 
of TIndexDef is created for each table index. 7/ndexDef- Field is 
a string containing the name of all the fields that comprise the 
index. The field names are separated by a semicolon. 


Again, there may be a more direct approach to obtaining informa- 
tion about the table's primary index. However, as with 7 Table. Fields, 
if we had used the /ndexFields property instead of IndexDefs, we 


would have been forced to work with an open table. 


Additionally, IndexFields only includes the names of the fields 
in the currently active index. If the primary index is not the 
active index, more work is needed to make the primary index 
the active index. 
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Another advantage of using /ndexDefs is that only minimal work 
is needed to increase the Table Documentor’s functionality so it 
can include the names of all the indices and fields that are used 
in each index. 


Like FieldDefs, IndexDefs requires a call to its Update method to ini- 
tialize each IndexDef object, and itself. Once FieldDefs and IndexDefs 
are initialized, the first of the two inner loops determines which 
table’s index is the primary index. The /ndexDefs. ltems[n]. Options 
property is evaluated to see if it’s of type zxPrimary. If so, the field 


names comprising the index are assigned to PrimIndxStr. 


Questions and Answers 

Next, we must store the text strings that will be printed or dis- 
played. But first, we need to answer this question: What is the 
best way to store, display, and print the strings? 


The 7Memo component on the Standard page of the 
Component Palette provides the answer. Many Delphi program- 
mers may not realize that a Memo component has two proper- 
ties for storing text — 7Memo. Text and TMemo.Lines. 


For our purposes, the 7ext property is too restrictive because 
the maximum length of its string is 255 characters. Conversely, 
the Lines property (a TStrings object) has no such limit, and 
initializing the strings with the Add method is easy. Therefore, 
the Table Documentor uses 7Memo.Lines for string storage. 


Before entering the final inner loop, three lines of header infor- 
mation are prepared. The first contains the table’s name and 
path. The second describes the meaning of the KeyFieldIndicator. 
The third call to Add initializes the column title line. 


The string’s display to the user is controlled by the call to 
Format. If you are unfamiliar with Delphi's Format function, the 
online help provides a good overview of its use (search on 
“Format Strings’). (Note that when using Format, any white 
space included in the format specifier list is interpreted literally.) 


In the final loop, two tests are performed to obtain information 
about the field before the string is concatenated. The first is per- 
formed so that if the data field’s size is returned as a zero, a 
blank can be displayed rather than the illogical zero value. The 
second performs a call to the Pos function. If the name of the 
current field is in the PrimIndxStr then Pos finds the match and 
returns the position of the first character. Therefore, for values 
greater than zero indicating that the field is included in the pri- 
mary key, the KeyChar is initialized with the KeyFieldIndicator. 


After these two tests, the string is ready to be built and added to 
Memo1.Lines. One more call is made to Format to concatenate the 
string that is used for the line containing the field information. 


Printing Table Structures 

Often, adding printing functionality to a program is a dreaded 
task because, at best, it tends to make for tedious programming. 
At worst, it adds a lot of bulk to a program. 
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{ This function is based on code from 
“Delphi Developer's Guide” by Xavier Pacheco & 
Steve Teixeira [Borland Press, 1995], pp. 297. } 


function TForm1.PrintStructures(var M: TMemo) Boolean; 
var 
X: integer; 
StructText: TExtFile; 
begin 
Result := True; 
if (M.Lines.Count = 0) then begin 
Result := False; 
MessageDlg('No tables selected for documenting...', 
mtInformation, [mbOK], 0); 
Exit; 
end; 


{ If PrintDialog1.Execute then we could give user 
option to setup printer } 

AssignPrn(StructText) ; 

try 
Rewrite(StructText) ; 
Printer.Canvas.Font.Assign(M.Font) ; 


for X := 0 to M.Lines.Count - 1 do 
writeln(StructText, M.Lines[X]); 
finally 
CloseFile(StructText) ; 
end; 
end; 


Figure 6: The TForm].PrintStructures function. 


While the technique used by the Table Documentor may not be 

suitable for all projects, it eliminates the arduous aspects of prepar- 
ing reports. In addition, the 24-plus line function that handles the 
printed output does not add any appreciable bulk to the program. 


As we've seen, GetStructures initializes a TMemo component's 
Lines property with data that describes a table. Now that the 
Lines object is properly formatted, our final task is to output 
each string’s value to the printer. This is accomplished by the 
PrintStructures function (see Figure 6). PrintStructures depends 
upon the Printers unit being listed in the program's uses clause. 
(Note that the code does not use the AsszgnPrn procedure 
declared in the WinPrn unit.) 


After some initial data integrity checking, the function assigns a 
text file to the current window’s default printer: 


AssignPrn(StructText) ; 


AssignPrn simply tells Windows that any output written to the 
text file should be sent to the printer using the 
TPrinter.Canvas.Font property. For this to happen, there must be 
a call to Rewrite that will create and open a new file. If the file 
exists, it will be overwritten. (Canvas. Font is initialized in Form1’s 
FormShow event handler to the fixed pitch font set at design 

time in the 7FontDialog component.) 


The Writeln statement accomplishes printing. It optionally 
accepts the name of a text file variable for its initial parameter 
and then writes all its output to that file. Next, a for loop is 
used to iterate through each string in the Memo1.Lines object 
and send the value of the strings to the printer via the 

Struct Text text file. 
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As mentioned earlier, the GetStructures function handles all the 
formatting. Note that the 7Memo’s WordWrap property was set 


to False at design time. 


Online Help 

Another aspect of the Table Documentor deserves review. It’s 
often nice to provide the user with some simple online help. 
Unfortunately, the application does not warrant the time 
required to create a Windows Help (.HLP) file complete with 
keywords and hypertext links. 


One way to handle this is to write a series of string constants that 
provide the necessary help, and then use a 7Memo component to 
display the strings. The Table Documentor uses this technique. 


The code from the /nfol Click procedure in the UStruct unit is 
shown in Figure 7. It initializes Form3 which contains the 
TMemo component that displays the help text. The text string’s 
constants are actually declared in the UHelp unit. A similar tech- 
nique for initializing the Form3.Memol’s Lines property was used 
in GetStructures. 


procedure TFormi.InfoiClick(Sender: TObject) ; 
begin 
{ Basic instructions: Simple programs don't require 
help files} 
{ Create form only as needed so as not to take up 
System resources } 
Form3 := TForm3.Create(Application) ; 
{ Initialize font } 
Form3.Memo1.Font := Form2.Memo1.Font; 
Form3.ShowInstructionsModal ; 
{ Release resources } 
Form3.Free; 
end; 


Figure 7: The TForm1.InfolClick procedure. 


A Note About Installation and the BDE 

Borland insists that the complete BDE and its installation utili- 
ty is distributed with all Delphi database applications. 
However, you may want to perform a partial install of the BDE 
when installing a program (for your use) requiring the BDE. 
Therefore, to add the Table Documentor to your arsenal of 
programming utilities, the entire BDE is not required. 


Assuming the BDE is not installed, to use the Table Documentor, 


you must create a directory into which you install the DLLs that 
make up the BDE, e.g. C:\IDAPI. Then edit WIN.INI to add an 
[IDAPI] group and add one line to that group: 


DLLPATH=C: \ IDAPI 
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Then copy the following files to the directory you just created 
and assigned to the DLLPATH variable: 

¢ IDAPIO1.DLL 

¢ IDR10009.DLL 

e IJLD01.DLL 

¢ IDAPI.CFG (with Delphi’s minimal default values) 

¢ JDPDX01.DLL (Paradox access) 

¢ IDDBAS01.DLL (dBASE access) 


After rebooting, the Table Documentor can be used without a 
complete BDE installation. These six files only occupy about 
1MB (uncompressed) as opposed to the entire BDE that 
occupies over 2MB. 


Concluding with a Challenge 

A how-to article should also challenge the user. Assuming that no 
program is ever complete, what features could be added to enhance 
the Table Documentor? If I were to write v2.0, it would report more 
details about a table’s properties. It would be cool to know about 
validity checks, table lookups, and secondary indices, to name a few. 


I would also alter the interface slightly by using a tabbed 
notebook metaphor. One page would contain the components 
on the current main form and the other page would contain 
the memo object showing the table structures. When the user 
clicks on Show Structures, the code would change pages. I 
think that this would be slicker and cause less screen clutter. 


Additionally, the form could be minimized and later opened to 
reference the structure listings without having to locate the child 
form among all the open windows. If anyone makes these modi- 
fications, please e-mail a copy of your efforts to me. Thanks! A 


Figure 6 is based upon Object Pascal code shown on page 297 of 
Delphi Developers Guide by Xavier Pacheco and Steve Teixeira 
[SAMS, 1995]. 


The sample Table Documentor application described in this 
article, and the About box freeware written by Jeff Atwood, are 
available on the Delphi Informant Works CD located in 
INFORM\96\MAR\DI9603KT: 


Karl Thompson is an independent Delphi and Paradox developer serving clients from 
New York City to Philadelphia. He has been working with Borland’s Pascal develop- 
ment environments since 1984. He can be reached at (609) 470-1430, or on 
CompuServe at 72366,306 (Internet: 72366.306@compuserve.com.). 
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